Skip to main content
Antes de apontar tráfego real para sua integração, percorra este checklist. Cada item representa uma classe de problema que já vimos em deploys — melhor resolver antes do que correr atrás depois.

​
Autenticação e segredos

Nenhuma chave hardcoded no código. Verifique com:
git grep "tly_live_" --  # deve retornar vazio
Use um gerenciador de secrets (Doppler, AWS Secrets Manager, HashiCorp Vault, Vercel env vars) em vez de .env comitado.
Revise cada API key e remova escopos desnecessários. Um serviço que só envia mensagens não precisa de agents:write nem contacts:write.
Confirme que o handler valida o header X-Timely-Signature antes de processar qualquer evento. Teste com um payload adulterado — deve retornar 401.
Defina uma data de rotação (sugestão: a cada 90 dias) e documente o procedimento interno. Veja o passo a passo em Autenticação → Rotacionando uma chave.

​
API e integração

Confirme que o código aponta para https://api.timelyai.com.br/v1 e que a x-api-key é do workspace de produção — não de um workspace de testes. Em CI/CD, use variáveis de ambiente distintas por stage.
Toda chamada à API tem lógica de retry que respeita o header Retry-After ao receber 429. Sem isso, picos de carga podem causar cascata de erros.
Se você busca listas (conversas, contatos, agentes), o código itera sobre todas as páginas usando meta.total_pages. Buscar só a página 1 pode omitir registros.
Configure timeout de no mínimo 15 segundos para chamadas à API. Requisições sem timeout travam workers indefinidamente em caso de lentidão de rede.

​
Webhooks

Confirme que a URL de webhook é acessível pela internet (não é localhost). Teste com:
curl -X POST https://seusite.com.br/webhook/timely \
  -H "Content-Type: application/json" \
  -d '{"test": true}'
O handler responde imediatamente e processa o evento de forma assíncrona (fila, worker). Processamentos síncronos que passam de 10 segundos causam retentativas desnecessárias.
O handler usa X-Timely-Event-Id para deduplicar eventos entregues mais de uma vez durante retentativas.
Eventos de webhook com falha ficam disponíveis no dashboard em Configurações → Webhooks → [endpoint] → Log de eventos. Configure um alerta interno se a taxa de falha subir acima de 1%.

​
Agentes e canais

Rode o test chat com pelo menos 20 variações de perguntas que seus clientes fariam. Inclua perguntas fora do escopo — verifique se o agente responde com educação e sem alucinar.
Defina a regra de handoff (palavra-chave, intenção, número de turnos sem resolução). Confirme que um atendente humano recebe a notificação corretamente.
Envie uma mensagem de um número real para o canal de produção e acompanhe o fluxo completo: recebimento → processamento pelo agente → resposta → log de conversa no CRM.
Se você usa envio proativo (fora da janela de 24h), os templates precisam estar aprovados pela Meta antes do go-live. Aprovação pode levar de 24h a 7 dias.

​
Monitoramento e alertas

Defina quem da equipe monitora o dashboard durante as primeiras 48h após o go-live. Identifique problemas antes que virem reclamação de cliente.
Em Configurações → Billing → Alertas, ative a notificação de saldo baixo. Créditos zerados pausam o envio de mensagens.
Guarde contato@timelyai.com.br na sua lista de contatos de incidente. Em casos críticos, mencione “URGENTE” no assunto.

​
Resumo visual

Segredos

API keys em variáveis de ambiente, escopos mínimos, webhook secret validado, rotacao planejada.

API

URL de producao correta, retry com backoff, paginacao completa, timeouts configurados.

Webhooks

Endpoint publico, resposta rapida, idempotencia, log de falhas monitorado.

Agentes e canais

Testes com cenarios reais, handoff configurado, canal testado end-to-end, templates aprovados.
Passou em tudo? Va em frente. Qualquer duvida de ultima hora, estamos em contato@timelyai.com.br.