msg_live_ foram desativados e não são mais aceitos.
O fluxo tem três partes:
1
Crie um OAuth Client no painel
Você recebe um
client_id e um client_secret permanentes.2
Troque as credenciais por um access token
Chame
POST /oauth-token. O token vale por 1 hora.3
Use o token nas chamadas
Envie
Authorization: Bearer <access_token> em cada requisição à API.Base URL
Todos os endpoints desta referência ficam sob a mesma base. A API só aceita HTTPS.Criar um OAuth Client
No painel, acesse Configurações → OAuth Clients.- Digite um nome para identificar a integração (ex.:
Loja virtual – Produção). - Clique em Criar.
- Copie o
client_id(começa comclient_) e oclient_secret(começa comsecret_).
Qualquer usuário com acesso ao painel da conta pode criar e revogar OAuth Clients.
Revogar um client
Na linha do client, clique em Revogar e confirme. A revogação vale na hora:- o client passa para Inativo e não pode ser reativado — para voltar a integrar, crie um client novo;
- todos os access tokens emitidos para ele deixam de funcionar imediatamente;
- o
client_idtambém deixa de valer nos scripts que rodam no navegador (Web Push e widget In-App) e no webhook do Telegram configurado com essa credencial.
Obter um access token
Veja o endpoint completo em POST /oauth-token. O corpo pode ser JSON ouapplication/x-www-form-urlencoded.
Resposta
Cada chamada a
/oauth-token emite um token novo; os anteriores continuam válidos até expirar. Guarde o token em cache e peça outro só perto do vencimento — os exemplos em Enviar mensagens renovam 1 minuto antes.
O endpoint
/oauth-token aceita até 30 pedidos por minuto por IP. Acima disso, responde 429 com {"error": "rate_limited", "retry_after": 60} e o header Retry-After.Usar o token
Envie o access token no headerAuthorization de toda chamada:
Formas de apresentar a credencial
O mesmo OAuth Client pode ser usado de três formas, cada uma para um tipo de chamador:
No par
client_id:client_secret, use dois-pontos sem espaços e cole os valores exatamente como aparecem no painel.
O
client_id não é segredo: ele só identifica a sua conta. Sozinho, não autoriza envio de mensagens nem leitura do histórico. Já o client_secret dá acesso total à API e nunca deve ir para o navegador.Nos scripts do navegador, o client_id também não prova quem é o usuário. Para isso, ligue a verificação de identidade descrita em Widget In-App: o seu servidor assina o userId com um segredo da conta, e a mesma regra vale para o sino e para o registro do Web Push.Erros comuns
Erros do/oauth-token:
Erros de autenticação nos demais endpoints:
Os endpoints de listagem de comunicações, estatísticas de envio e configuração de canal respondem
401 com {"error": "Unauthorized"} nos dois casos: header ausente ou credencial inválida.
Boas práticas de segurança
- Nunca exponha o
client_secretnem o segredo de verificação de identidade no frontend (JavaScript do navegador, app mobile). - Guarde as credenciais em variáveis de ambiente ou num cofre de segredos, fora do código.
- Reutilize o access token até perto da expiração, em vez de pedir um novo a cada envio.
- Use HTTPS em todas as chamadas.
- Se suspeitar de vazamento, revogue o client no painel e crie outro.