Skip to main content
Pegue o café. Você vai gerar uma chave, confirmar que a API está viva, listar seus agentes e enviar uma mensagem — tudo em sequência, tudo com exemplos prontos para copiar.
1

Gere sua API key

Acesse o Dashboard → Configurações → API Keys → Nova chave.
  1. Dê um nome descritivo (ex: backend-producao, n8n-integracao)
  2. Selecione os escopos necessários — para este quickstart, marque agents:read, conversations:write e messages:send
  3. Clique em Criar
  4. Copie a chave imediatamente. Ela só aparece uma vez.
Nunca exponha a API key no frontend ou em repositórios públicos. Use variáveis de ambiente em todo lugar.
Nos exemplos abaixo, substitua SUA_CHAVE pela chave gerada.
2

Teste o health check

Confirme que a API está respondendo e que sua chave é válida:
curl https://api.timelyai.com.br/v1/health \
  -H "x-api-key: SUA_CHAVE"
Resposta esperada:
{
  "data": {
    "status": "ok",
    "version": "1.0.0",
    "timestamp": "2026-04-19T12:00:00Z"
  }
}
Se receber 401, a chave está inválida ou expirada. Verifique em Configurações → API Keys.
3

Liste seus agentes

Agora busque os agentes configurados no seu workspace:
curl "https://api.timelyai.com.br/v1/agents?page=1&per_page=10" \
  -H "x-api-key: SUA_CHAVE"
Guarde o id do agente que vai usar no próximo passo.
4

Envie uma mensagem via agente

Com o agent_id em mãos, envie uma mensagem para um contato. A API cria a conversa automaticamente se não existir.
curl -X POST https://api.timelyai.com.br/v1/messages/send \
  -H "x-api-key: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "AGENT_ID",
    "contact": {
      "phone": "+5511999998888",
      "name": "João Teste"
    },
    "message": "Olá! Como posso te ajudar hoje?",
    "channel": "whatsapp"
  }'
Resposta de sucesso (201 Created):
{
  "data": {
    "message_id": "msg_abc123",
    "conversation_id": "conv_xyz456",
    "status": "queued",
    "created_at": "2026-04-19T12:05:00Z"
  }
}
O campo status: "queued" indica que a mensagem foi aceita e está em fila de envio. Use webhooks para acompanhar a entrega em tempo real.

​
Próximos passos

Autenticação e escopos

Entenda todos os escopos disponíveis e boas práticas de segurança.

Webhooks

Receba eventos em tempo real: mensagens, conversas encerradas, handoffs.

Rate limits e erros

Limites por minuto, paginação e todos os códigos de erro da API.

Referência completa da API

Todos os endpoints com playground interativo.