Versão: 1.0.0

Atalia API

API da plataforma Atalia para gerenciamento de atendimento multicanal.

Autenticação

A Atalia tem duas credenciais de API, e cada uma abre um conjunto de rotas. Elas não se substituem: usar a credencial errada responde 401 com um code que diz qual usar (COMPANY_KEY_NOT_ALLOWED ou PERSONAL_TOKEN_NOT_ALLOWED).

	Chave da empresa	Token pessoal
Formato	atk_live_ + 32 caracteres	Gerado no Perfil
Onde gerar	Chave e webhook (modo de integração) ou Configurações › Integração via API	Configurações › Perfil › Token pessoal (avançado)
De quem é	Da empresa	De um usuário
O que abre	Só as rotas de Integração (/api/v1/...)	As demais rotas desta referência (/api/...), com o mesmo acesso que o usuário tem no painel
Qual empresa	A da chave. Não envie X-Company-Id	A do usuário. Com mais de uma, escolha com X-Company-Id
Quando alguém sai da equipe	Continua valendo	Para de funcionar, se for o dono do token
Use para	O sistema que envia e recebe mensagens pelas caixas de entrada, com webhook	Scripts e relatórios: conversas, contatos, agentes, times, templates

As duas vão no mesmo header, x-api-key (ou Authorization: Bearer <credencial>):

x-api-key: sua-credencial

As duas aparecem inteiras uma única vez, ao gerar, e gerar uma nova invalida a anterior. Use só no servidor: nunca em código que roda no navegador ou no app.

Chave da empresa (Integração)

É a credencial recomendada para ligar um sistema à Atalia. Ela abre as rotas da seção Integração: listar as caixas de entrada, enviar mensagens (texto, template, mídia, botões), consultar a situação de uma mensagem e baixar mídia. As mensagens recebidas não são lidas pela API: chegam no seu webhook, assinadas. Veja o guia Integração via API e a referência completa em texto, feita também para IAs: llms.txt.

• A empresa vem da chave. X-Company-Id não é usado nessas rotas.
• Revenda: a mesma chave enxerga as caixas de entrada dos seus clientes; cada uma vem com client_id. Veja Conectar os números dos seus clientes.
• Erros nessas rotas vêm como { "error": { "code": "...", "message": "..." } }.

Token pessoal

Age em nome do usuário que o gerou, com o acesso que ele tem no painel. Serve para automações e relatórios sobre o atendimento feito na Atalia (conversas, contatos, agentes, times). Requisições de escrita vindas de origens de navegador não autorizadas são rejeitadas com status 403.

Contas com mais de uma empresa (token pessoal)

O token pertence a um usuário, não a uma empresa. Se o seu usuário tem acesso a mais de uma empresa, informe qual delas deve ser usada no header X-Company-Id; sem ele, a empresa selecionada é indeterminada.

Para descobrir os IDs, chame GET /api/me: o campo companies lista as empresas do usuário, com o id de cada uma. Em todos os endpoints do token pessoal o cabeçalho aparece em Cabeçalhos e no campo X-Company-Id do botão Enviar requisição.

x-api-key: seu-token-pessoal
X-Company-Id: 42

Com a chave da empresa não existe essa escolha: cada chave é de uma empresa só.

Testando por esta documentação

Logado no painel, o teste usa a sua sessão, não o token

Se você está logado na Atalia neste navegador, o botão Enviar requisição das páginas do token pessoal manda junto o cookie da sua sessão. A sessão tem prioridade sobre o token: a requisição responde mesmo sem x-api-key, e um token preenchido é ignorado. Os dados que voltam são os do seu usuário, na empresa da sua sessão. Nas rotas de Integração a sessão não vale: só a chave da empresa.

Fora do navegador (o seu servidor, o cURL, o Postman) não existe essa sessão: só a chave vale. Para conferir se a sua chave funciona, teste numa janela anônima ou saia do painel antes.

Caminhos antigos (/api/protected/...)

Os endpoints ficam em /api/<recurso>, por exemplo GET /api/conversations. Até outubro de 2026 eles eram documentados com o prefixo /api/protected/, e esse caminho continua funcionando: /api/protected/conversations responde igual a /api/conversations. As respostas pelo caminho antigo trazem o header Deprecation: true; ao atualizar a sua integração, use o caminho novo.

Formato de Resposta

Todas as respostas são em JSON. Em caso de erro:

{
  "error": "Descrição do erro"
}

Alguns erros trazem também um campo code para tratamento programático: INVALID_API_KEY (token inválido ou revogado), COMPANY_ACCESS_DENIED (o token não tem acesso à empresa informada em X-Company-Id) e COMPANY_KEY_NOT_ALLOWED (chave da empresa usada numa rota do token pessoal). As rotas de Integração têm formato próprio, descrito na seção delas.

Paginação

Endpoints de listagem aceitam page e limit e retornam um objeto pagination. Atenção a duas diferenças entre recursos:

• Conversas e mensagens usam totalPages; contatos usam pages.
• Em GET /api/conversations, os campos total e totalPages vêm como null por padrão, porque a contagem é servida por um contador incremental. Para obter os totais, envie filter_modal=true ou search.

Authentication

API Key: apiKeyAuth

Token pessoal, gerado em Configurações → Perfil → Token pessoal (avançado). Age em nome do usuário. O header Authorization: Bearer <token> é equivalente.

Security Scheme Type:	apiKey
Header parameter name:	x-api-key

HTTP: Bearer Auth

Mesmo token pessoal, no formato Authorization: Bearer <token>.

Security Scheme Type:	http
HTTP Authorization Scheme:	bearer

API Key: companyKeyAuth

Chave da empresa (atk_live_...), gerada em Chave e webhook (ou em Configurações › Integração via API no painel completo). Só abre as rotas de Integração (/api/v1). O header Authorization: Bearer <chave> é equivalente.

Security Scheme Type:	apiKey
Header parameter name:	x-api-key

HTTP: Bearer Auth

Segredo de identificação do canal de webchat (gerado em Editar canal → Identificação de usuários), não a chave de API pública geral. Usado exclusivamente pelos endpoints da tag Webchat. Ver Identificação de usuários no Webchat.

Security Scheme Type:	http
HTTP Authorization Scheme:	bearer

Contact

Atalia Support: suporte@atalia.ai