API para desenvolvedores
Envie uma DM com um único POST.
Uma API REST para o seu CRM no plano Business: contatos, conversas, negócios, tarefas, campanhas e mensagens no Telegram, no X e na caixa de entrada social. Autenticação Bearer, chaves com escopo, idempotência, cabeçalhos de limite de taxa e webhooks de saída. Sem precisar de SDK.
- JSON sobre HTTPS
- Respostas de baixa latência
- Confiável por design
Última atualização:
O mesmo endpoint. Quatro linguagens.
Um único contrato JSON. Copie, cole e coloque no ar. A especificação OpenAPI completa documenta cada endpoint, cada erro e cada payload de webhook.
curl -X POST https://api.pinlyx.com/v1/telegram/messages \ -H "Authorization: Bearer csk_live_***" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"accountId":7421,"username":"sarah_miller","text":"Boas-vindas a bordo"}'Referência completa e catálogo de erros em docs.pinlyx.com/api
Chaves com escopo. Privilégio mínimo por padrão.
Gere chaves de API com escopo: somente leitura para painéis de análise, escrita para os envios em produção e gestão para a automação operacional. Faça a rotação sem tempo fora do ar: as chaves convivem durante a troca, então nada quebra.
Autenticação Bearer
Envie
Authorization: Bearer csk_live_…em toda requisição. Chaves de produção e de teste são visualmente diferentes, para que os fluxos em produção fiquem protegidos.Permissões por escopo
Escolha o menor conjunto de escopos de que a chave precisa. Uma chave de painel vazada nunca consegue enviar uma mensagem.
Rotação sem tempo fora do ar
Emita uma chave substituta, faça o deploy e depois revogue a antiga. As duas valem durante a janela de transição, sem uma avalanche de erros 401.
contacts:readListar, buscar e ler contatos e as conversas deles.telegram:readConsultar o status de uma mensagem de Telegram na fila.analytics:readPuxar estatísticas de funil, campanhas e contas.telegram:sendColocar na fila mensagens de Telegram das suas próprias contas.contacts:writeCriar, atualizar e etiquetar contatos.sequences:writeInscrever contatos em campanhas, pausar e retomar.webhooks:writeRegistrar endpoints de webhook e fazer a rotação deles.
Controle de fluxo que conta tudo para você.
Com chaves de idempotência, repetir uma requisição é seguro: a mesma mensagem nunca sai duas vezes. Os cabeçalhos de limite de taxa avisam o seu cliente quando desacelerar, antes mesmo de chegar um 429.
- X-RateLimit-Limit
- 60
- # requisições por minuto, por chave
- X-RateLimit-Remaining
- 48
- # restantes na janela atual
- X-RateLimit-Reset
- 1778077380
- # horário Unix em que a janela reinicia
- Retry-After
- 12
- # em caso de 429, espere esta quantidade de segundos
Chaves de idempotência
Envie
Idempotency-Keyem toda escrita. Uma nova tentativa com a mesma chave em até 24 horas devolve a resposta original em vez de enviar de novo.Limites de taxa por chave
Cada chave de API permite 60 requisições por minuto por padrão, com ajuste por chave. Depois, os envios no Telegram seguem o ritmo da própria conta: 20 mensagens por hora e um intervalo de 10 segundos por padrão, com espera automática em caso de flood wait.
Catálogo de erros estável
Todo erro devolve um campo
Errorestável para a sua lógica decidir o que fazer, além de um campoMessageem linguagem clara para mostrar ao usuário, no mesmo formato JSON em todos os endpoints.
Webhooks de saída para cada evento.
Receba 31 eventos do CRM em tempo real. Assinaturas HMAC-SHA256, novas tentativas automáticas com espera exponencial e um registro de entregas onde você pode reenviar qualquer entrega.
- message.sent
- contact.created
- pipeline.stage_changed
- sequence.completed
- outreach.replied
- task.completed
- support.ticket.created
- subscription.changed
{ "event": "message.received", "id": "8c1f4b9e2d7a4c03b5e6f1a2", "deliveredAt": "2026-05-06T14:32:18Z", "channel": "telegram", "contactId": 8821, "counterparty": "@sarah_miller", "text": "Oi, pode me mandar a demo?"}const sig = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');if ('sha256=' + sig !== headers['x-webhook-signature']) return 401;Quando você quiser começar
Construa com o Pinlyx. No ar em minutos.
No plano Business, você cria uma chave no painel, cola um curl e vê a mensagem entrar na fila. A referência OpenAPI documenta cada endpoint e cada erro.
- No plano Business
- Chaves criadas no painel
- Webhooks assinados com HMAC